It’s never final

Requirements for good version control

• Complete and long-term history of every file in your project
• Safe (e.g. no accidental loss of versions)
• Easy to use
• Document all changes: what, why, who, when
• Allow for collaboration
• Online version for backup and sharing
• Offline version for working on the project

Requirements for good version control

• Complete and long-term history of every file in your project
• Safe (e.g. no accidental loss of versions)
• Easy to use
• Document all changes: what, why, who, when
• Allow for collaboration
• Online version for backup and sharing
• Offline version for working on the project

Git checks all the boxes!

What is Git?

• Open source and free to use version control software
• Quasi standard for software development
• A whole universe of other software and services built on top of it

What is Git?

• For projects with mainly text files (e.g. code, markdown files, …)

• Basic idea: Take snapshots (commits) of your project over time

What is Git?

Git is a distributed version control system

How to use Git?

After you installed it there are different ways to interact with the software.

How to use Git - Terminal

Using Git from the terminal

How to use Git - Integrated GUIs

A Git GUI is integrated in most (all?) IDEs, e.g. R Studio, VS Code

How to use Git - Standalone GUIs

Standalone Git GUI software, e.g. GitHub Desktop, Source Tree, …

How to use Git?

• Depends on experience and taste
• You can mix methods because they are all interfaces to the same Git
• We will use the GitHub Desktop GUI
  • Beginner-friendly, intuitive and convenient
  • Nice integration with GitHub

Example

A cook book project to collect all my favorite recipes.

Step 1: Initialize a Git repository

Step 1: Initialize a Git repository

Step 1: Initialize a Git repository

Step 2: Add and modify files

Git detects any changes in the working directory

Step 2: Stage changes

Staging a file means to list it for the next commit.

Step 2: Stage changes

Staging a file means to list it for the next commit.

Step 3: Commit changes

Commits are the snapshots of your project state

Step 3: Commit changes

Commits are the snapshots of your project state

Step 3: Commit changes

Changes are part of Git history and staging area is clear again

How to write good commit messages?

How to write good commit messages?

Add pie recipe

This is my favorite pie in the world. 
The recipe comes from my grandfather and 
he learned it from his neighbor.

added a file.

This is really good.

The commit history

Step 4: Share changes with the remote repo

Use remote repos to synchronize, share and collaborate (can be public or private/for collaborators only)

Step 4: Share changes with the remote repo

Use remote repos to synchronize, share and collaborate (can be public or private/for collaborators only)

Publishing your projects

• There are commercial and self-hosted options for your remote repositories
  • Commercial: GitHub, GitLab, Bitbucket, …
  • Self-hosted: GitLab (maybe at your institution?)
• Please be aware of your institutional guidelines
  • Servers might be outside EU (e.g. GitHub)
  • Privacy rules might apply depending on type of data

Why publish?

Advantages for scientists

• Visibility and Credit
• Others can build on your work
• Citations
• Reproducibility
• Get feedback

Summary of the basic steps

• git init: Initialize a git repository
  • Adds a .git folder to your working directory
• git add: Add files to the staging area
  • This marks the files as being part of the next commit
• git commit: Take a snapshot of your current project version
  • Includes time stamp, commit message and information on the person who did the commit
• git push: Push new commits to the remote repository
  • Sync your local project version with the remote e.g. on GitHub

Revert changes

• Use git revert to revert specific commits
• This does not delete the commit, it creates a new commit that undoes a previous commit
  • It’s a safe way to undo commited changes

Ignore files with .gitignore

• Git tracks all files in your working directory
• Often, we have files we do not want tracked
  • Personal notes
  • Compiled code and build directories
  • Log files
  • Hidden system files
  • Personal IDE config files
  • …

Ignore files with .gitignore

• Create a file with the name .gitignore in working directory
• Add all files and directories you want to ignore to the .gitignore file

# Ignore single files

my_notes.docx  # ignore the file my_notes.docx
debug.log # ignore the file debug.log


# Ignore files with specific endings

*.html    # ignore all .html files
*.pdf     # ignore all .pdf files

# Ignore directories

build/    # ignore all files in subdirectory build

Git

• Commit often (small changes that can be described in one commit message)
• Write good commit messages (it becomes a habit)
• Push (at least) daily (backup!)
• Use .gitignore
• Don’t commit secrets

Publishing

Some essentials that will improve your published repository:

• Add a good README.md file
  • Tell people what your project is about and how to use it
  • Check out the GitHub documentation for formatting options
• Add a LICENSE file
  • Tell others how to use your code
• Add a DOI to your repository (e.g. via Zenodo)

Checkout a previous commit

Take your work space back in time temporarily with git checkout

Preparation for tomorrow

• Tomorow we have teams of 2
• Collaborate on the cook book of your team mate

Preparation for tomorrow

1. Enter your GitHub Account Name and the link to your repo here

Preparation for tomorrow

1. Enter your GitHub Account Name and the link to your repo here
2. Look for the GitHub Name of your team mate and add them as a collaborator to your repository

Preparation for tomorrow

1. Enter your GitHub Account Name and the link to your repo here
2. Look for the GitHub Name of your team mate and add them as a collaborator to your repository
3. Accept the invitation of your team mate to their repository

• You will get an Email or you can do it on GitHub